Suppliers v1

The import/suppliers endpoints allows you to import the suppliers properties.

Authorisation

A function key is required. The name of Key must match Software Key

Request format

Method and URL

The HTTP method and URL is as follows:

HTTP

POST https://payandbill-cloud-api.azurewebsites.net/api/import/suppliers?version=1

Request Headers

Name	Type	Description
header	X-Functions-Key	Function Api Key
header	X-Software-Key	Software Key for this Integration

Request Body

Name	Type	Description
body	Suppliers[]	Suppliers schema

Request Body Example

Example Request Body

[
  {
    "EmployerRef": "ER1",
    "SupplierRef": "SUPPLIER1",
    "LegalStatus": "CIS",
    "SupplierType": "Umbrella",
    "BusinessName": "Supplier Co Name",
    "Address": {
      "AddressLine1": "First Line of Address",
      "AddressLine2": "Second Line of Address",
      "AddressLine3": "Third Line of Address",
      "AddressLine4": "Fourth Line of Address",
      "AddressLine5": "Fifth Line of Address",
      "Postcode": "PC1",
      "Country": "UK"
    },
    "IncorporationDate": "2018-01-01T00:00:00",
    "CompanyRegNo": "1234",
    "VATNumber": "123456",
    "VATCodeSource": "SpecifiedVATRate",
    "DefaultVATRate": "S",
    "DivisionRef": "DIV1",
    "DepartmentRef": "DEPT1",
    "PurchaseLedgerAccountNumber": "PL1",
    "PaymentOption": "PaidViaTimesheets",
    "PaymentTermsValue": 7,
    "PayMethod": "BACS",
    "CurrencyRef": "GBP",
    "IsSelfBillingEnabled": true,
    "SelfBillingInvoiceBreakLevel": "Worker",
    "SupplierNotes": "Supplier Notes",
    "EmailAddress": "supplier@sampledata.co.uk",
    "PayslipPrintMethod": "Paper",
    "IsPaidWhenPaid": false,
    "TaxReferenceNumber": "123456",
    "IsOn46GReport": false,
    "BankDetails": {
      "BankSortCode": "654321",
      "BankAccountNumber": "987654321",
      "BankAccountName": "Bank Account Name",
      "IBAN": "IBAN 2",
      "BIC": "BIC 2"
    },
    "CISDetails": {
      "CISUniqueTaxReference": "987654321",
      "CISLegalStatus": "LimitedCompany",
      "CISPartnershipName": "CIS Partnership",
      "CISPartnershipUTR": "123456789"
    }
  }
]

Responses

Name	Type	Description
200 Ok	Results[]	successful operation
400 Bad Request	string	Invalid Json request or Invalid DB Version
401 Unauthorized	string	Invalid/Missing API Key
403 Forbidden	string	Key name does not match Software Key
403 Forbidden	string	Integration missing for Software Key or disabled
403 Forbidden	string	Pay and Bill Database not active
501 Not Implemented	string	Message Type not found/implemented
501 Not Implemented	string	Payload data not supported

Response Example

Example Response

{
    "results": [
        {
            "recordIds": [
              {
                    "field": "EmployerRef",
                    "value": "1308"
                },
                {
                    "field": "SupplierRef",
                    "value": "SUP1"
                }
            ],
            "importStatus": "OK",
            "errorCount": 0,
            "warningCount": 0,
            "infoCount": 0
        }
    ]
}

400 Response

Response when Invalid Json Request Body is sent to API.

Message will contain parsing error message.

400 Error Response

{
  "message": "<string>"
}

200 Response

A results array is returned which will include an item for each array item in the original request body.

Each item will identify the recordId's relevant for this message type.

Import Status, errorCount & warningCount will indicate the status of that row.

Messages will contain any error/warning messages relevant.

Note: Each row is treated as a separate commit to the database, so if multiple items are included in the import, the response will indicate which have been imported successfully & which have failed to import.

200 Ok Response

{  "results": [
    {
      "recordIds": [
          "field": "<string>",
          "value": "<string>"
       ],
       "importStatus": "<string>",
       "errorCount": <number>,
       "warningCount": <number>,
       "messages": [
         {
            "messageType": "<string>",
            "message": "<string>",
            "fieldName": "<string>"
         }
       ]
    }
  ]
}

Results

This is the response output from the import/suppliers endpoint

Property	Type	Defined
RecordIds	recordIds[]	Suppliers Results
ImportStatus	string	Suppliers Results
ErrorCount	integer	Suppliers Results
WarningCount	integer	Suppliers Results
InfoCount	integer	Suppliers Results
Messages	messages[]	Suppliers Results

RecordIds

A record id of the imported Suppliers

RecordIds

• Type: array

Property	Type	Defined
Field	string	Suppliers Results
Value	string	Suppliers Results

Example

{
    "recordIds": [
        {
           "field": "EmployerRef",
           "value": "1308"
       },
       {
           "field": "SupplierRef",
           "value": "12345"
       }
   ]
}

ImportStatus

The import status of the request

ImportStatus

• Type: string

• defined in: Suppliers Results

ErrorCount

Number of errors in the request

ErrorCount

• Type: integer

• defined in: Suppliers Results

WarningCount

Number of warnings in the request

WarningCount

• Type: integer

• defined in: Suppliers Results

InfoCount

Number of Information messages in the request

InfoCount

• Type: integer

• defined in: Suppliers Results

Messages

An output of the info, warning or error messages.

Messages

• Type: array

Property	Type	Defined
MessageType	string	Suppliers Results
Message	string	Suppliers Results
FieldName	string	Suppliers Results
FieldValue	string	Suppliers Results
ErrorId	integer	Suppliers Results

Example

{
    "messages": [
        {
           "messageType": "Error",
           "message": "Required field missing or empty",
           "fieldName": "BusinessName",
           "errorID": 1001
        }
   ]
}